Introduction

This document is addressed to Torque committers who wish to edit and deploy the Torque site. If you find anything missing or wrong, please edit this document. If you find any procedure unsatisfactory, change it and document it here :-).

Organisation of the site's source code

The Torque site consists of a "frame site" and the "sites" of the various components of Torque (== maven subprojects). The sites of the components are embedded in the main site (i.e. the user does not see that he has entered the component's site, as the navigation on the left hand side looks the same). In contrast to the subprojects, the "frame site" has no tags and branches in svn. (This is why you cannot get the frame site from the trunks svn directory).

Each subproject keeps its documentation in its own xdocs subdirectory. Currently, the templates subproject does not have its own documentation. There is also a subproject (docs-all-components) which contains documentation which affects mor than one subproject.

Adding new documentation

If you want to add new documents, please think about where they should be added:

  • If they affect only one component of Torque, add them to the xdocs of the component.
  • If the new documents affect Torque as a whole, add them to the site subproject.

Editing the navigation

As the navigation should look "the same" from the main site and each subproject, changes made to the "frame navigation", i.e. the navigation items which can be seen from every page of the site, must be made in the site subproject and the site of every component alike. (Probably there is some way to script this, but as this will probably be very different for a Maven 2 build, I do not think it is worth while now.)

If the change in the navigation affects a place which can not be seen from everywhere in the project (e.g. a new item in the "references" section of the runtime docs), there is no need to update the navigation.xml's of the other subprojects and the frame site.

Deploying the site

This is a step-by-step guide to deploy the whole site. If you only want to deploy the documentation for a subproject, omit the steps to be omitted from the description below. The guide assumes that the necessary ssh properties and maven properties are set.

  • It might be a good idea to create a tar.gz backup of the current state of the site in your home directory, in case anything goes wrong.
  • Build the sites of the frame site and the components using "maven site" in each project. This might take a while because of the linkchecking.
  • Deploy the frame site and the components using "maven site:deploy". The frame site will be deployed to the correct place. The sites of the subprojects will be deployed to db.apache.org/torque/${subproject-name}, where they are not visible.
  • Move the sites of the subprojects to the correct place, db.apache.org/torque/releases/torque-${version}/${subproject-name}. (Probably this step can be automated by changing the siteDirectory in the pom, I have not tested this.)
  • Empty the cache of your browser and check everything is ok on http://db.apache.org/torque/
  • If you are satisfied with the new site and noone complains during the next few days, delete the backup tar.gz.

Updating the site for a new release

The following steps are necessary if a new release is created. I have not tested the procedure, so think yourself instead of following blindly (as always :-) )

  • Create a backup tar.gz of the site AND copy the whole site to your apache home directory for the site archive.
  • In the _COPY_ of the site for the archive, remove the previous versions in the releases/ subdirectory. E.g. if the current version is Torque 3.3 and you want to create the site for the release of Torque 4.0, remove everything except the torque-3.3 subdirectory of the releases directory.
  • Add the old version to the "Previous Releases" section in the navigation.xml of the frame site. Also, change the release number in all navigation.xml's to the new current release number.
  • Deploy the whole site (see above).
  • Clean the directory of the previous version in the new version of the site (NOT in the copy) (in the above examples, this would be removing releases/torque-3.3/runtime, releases/torque-3.3/generator and so on.)
  • Now copy the copy of the old site to the freshly cleaned subdirectory of the releases/ directory. The idea is that the "old" http://db.apache.org/torque.index.html is now available under http://db.apache.org/torque/releases/${old.version}/index.html, and so on.
  • Remove the old dev version (if it exists) from the releases subdirectoy (in our above eample, this would be releases/torque-3.3-dev).
  • Empty your browser cache and check the results.